/******************************************************************************
 * @file     bsp_led_driver.c
 * @brief    led driver层
 * @author   Ruilist
 * @date     2025-08-13
 * @version  V1.0.0
 * @copyright Copyright (c) 2025
 *
 * @note     1 tab = 4 space
 *           依赖 <stdio.h>
 *           依赖 <stdint.h>
 *
 * @par 日志:
 * - V1.0.0 2025-08-13 Ruilist
 *****************************************************************************/

#ifndef __BSP_LED_DRIVER_H__
#define __BSP_LED_DRIVER_H__

//******************************** Includes *********************************//

#include <stdint.h>
#include <stdio.h>

//******************************** Includes *********************************//

//******************************** Defines **********************************//

#define OS_SUPPORTING  // 支持OS操作系统
#define DEBUG          // 开启DEBUG模式

#ifdef DEBUG
#define DEBUG_OUT( X ) printf( X ) /*DEBUG调试信息输出接口*/
#endif                             // DEBUG

#define NOT_INITED 0  // led实例已初始化
#define INITED     1  // led实例已初始化

typedef struct bsp_led_driver bsp_led_driver_t;

/**
 * @brief LED操作状态枚举
 */
typedef enum
{
    LED_OK              = 0,     // 表示LED操作成功
    LED_ERROR           = 1,     // 表示LED操作中出现了一般错误
    LED_ERROR_TIMEOUT   = 2,     // 表示LED操作超时
    LED_ERROR_RESOURCES = 3,     // 表示资源不足，无法完成LED操作
    LED_ERROR_PARAMETER = 4,     // 表示传入的参数无效
    LED_ERROR_NOMEMORY  = 5,     // 表示内存不足，无法完成LED操作
    LED_ERROR_ISR       = 6,     // 表示ISR（中断服务例程）中发生了错误
    LED_ERROR_BUSY      = 7,     // 表示LED忙，无法执行操作
    LED_ERROR_RESERVED  = 0XFF,  // 保留的错误码，用于未来扩展
} led_status_t;

/**
 * @brief LED闪烁占空比枚举
 */
typedef enum
{
    DUTY_CYCLE_1_1 = 1,     // 闪烁占空比1:1
    DUTY_CYCLE_1_2 = 2,     // 闪烁占空比1:2
    DUTY_CYCLE_1_3 = 3,     // 闪烁占空比1:3
    DUTY_CYCLE_x_x = 0xFF,  // 闪烁占空比x:x 用于后续扩展
} led_duty_cycle_t;

/**
 * @brief LED操作函数指针结构体
 */
typedef struct
{
    led_status_t ( *pf_led_on )( void );   // LED使能函数
    led_status_t ( *pf_led_off )( void );  // LED失能函数
} led_operations_t;

/**
 * @brief 时基函数指针结构体
 */
typedef struct
{
    led_status_t ( *pf_get_time )( uint32_t *const );  // 获得时基函数
} time_base_t;

#ifdef OS_SUPPORTING
/**
 * @brief OS延时函数指针结构体
 */
typedef struct
{
    led_status_t ( *pf_os_delay )( const uint32_t );  // 获得OS延时函数
} os_delay_t;
#endif  // OS_SUPPORING

/**
 * @brief LED控制函数指针类型定义
 */
typedef led_status_t ( *pf_led_control )( bsp_led_driver_t *const,
                                          uint32_t,         // 闪烁周期(ms)
                                          uint32_t,         // 闪烁次数
                                          led_duty_cycle_t  // 闪烁占空比
);

/**
 * @brief BSP层LED驱动结构体
 */
typedef struct bsp_led_driver
{
    uint8_t           init_status;  // 实例初始化状态
    uint32_t          cycle;        // 闪烁周期(ms)
    uint32_t          blink_times;  // 闪烁次数
    led_duty_cycle_t  duty_cycle;   // 闪烁占空比
    led_operations_t *p_led_ops;    // led亮灭操作函数指针
    time_base_t      *p_time_base;  // 时基函数指针
#ifndef OS_SUPPORTING
    pf_led_control pf_led_controler;  // led特性操作函数指针
#endif                                //! OS_SUPPORTING

#ifdef OS_SUPPORTING
    os_delay_t *p_os_delay;  // OS延时函数指针
#endif                       // OS_SUPPORING
} bsp_led_driver_t;

//******************************** Defines **********************************//

//******************************** Declaring ********************************//

/**
 * @brief   led实例挂载函数
 *
 * @param   bsp_led_driver_t *const self     led实例结构体指针
 * @param   led_operations_t *const led_ops  led亮灭操作函数指针
 * @param   time_base_t *const time_base     时基函数指针
 * @param   os_delay_t *const os_delay       OS延时函数指针
 *
 * @return  led_status_t 函数运行状态
 *
 * @retval  LED_OK                操作成功
 * @retval  LED_ERROR_PARAMETER   传入参数错误
 */
led_status_t led_driver_inst( bsp_led_driver_t *const self,
                              led_operations_t *const led_ops,
                              time_base_t *const      time_base,
#ifdef OS_SUPPORTING
                              os_delay_t *const os_delay
#endif  // OS_SUPPORTING
);

//******************************** Declaring ********************************//

#endif  // End of __BSP_LED_DRIVER_H_
